chore(secrets): bump secretspec to v0.20, thread an audit reason, and stage an age-capable CLI (RIG-3320) - #916

…r (RIG-3320)

setArgs used the joined --flag=value form for --reason and --file but
left --provider and --profile in the two-token form the same function's
comment declares unsafe. That rationale is a property of the value's
shape, not of which flag carries it: ValidateProfile admits a leading
dash and the provider URI is unvalidated, so a dash-leading value was
parsed as the next flag and the CLI exited 2 — surfacing through
SetSecret as a misleading retryable CodeUnavailable rather than a
config error. Join all four, and cover the operator-configured flags in
the hostile-input test that previously exercised only reason.

The version-floor test's failure message and devenv.yaml both cited a
0.15 age floor, contradicting the design record's 0.17. Upstream's
changelog puts age:// under 0.17.0, so the record was right and both
citations are corrected rather than the record.

Also refresh three stale artifacts: WithProfile's doc still promised the
SDK default an explicit --profile now precludes, the record's Load
citation still named the v0.15.0 pin (re-verified at v0.20.0
secretspec.go:293 — still no ctx, so the offload design stands), and the
audit reason was anonymous despite the handler holding the caller ID,
which is half the provenance the reason exists for.

Refs RIG-3320

Co-authored-by: Matt Wilkinson <matt@rigel.build>

…it-reason contract (RIG-3320)

Round-3 review findings, all documentation/coverage — no behavior change.

- Design record: the round-3 commit added 5 lines to resolver.go and silently
  invalidated 23 file:line citations in the record it also edits. Re-point them
  all to the head tree, and fix the two SDK binding citations left at their
  v0.15.0 offsets inside the very sentence that was refreshed to v0.20.0
  (binding_cgo.go:30 -> :28, binding_purego.go:118 -> :142).
- resolver.go: the Set doc comment still illustrated the two-token
  '--provider <p> --profile <P>' form that the next sentence declares broken and
  that setArgs no longer emits. Show the joined form and the widened
  value-shape scope.
- secrets_service.go: lead the audit-reason comment with the structural
  guarantee (callerID is a bearer-resolved, server-minted hex account id, never
  a request field) and keep the CLI's JSON escaping as defense in depth.
- secrets_service_pgtest_test.go: the caller-bound audit reason was a new
  observable contract with no test. Bind the assertion to the authenticated
  user's account id and pin that the reason never carries the value.

Refs RIG-3320

Co-authored-by: Matt Wilkinson <matt@rigel.build>

…tale v0.15 claims (RIG-3320)

Round-4 review findings. No behavior change.

- Design record: round 4 swept resolver.go citations only, but commit 1 shifted
  go/server/secrets_service.go by +10 lines, so four citations pointed at
  real-but-wrong code — including the F1 master-key guard's placement, which
  named an audit comment and a nil-resolver early return instead of the two
  resolver call sites. Re-point them, and audit EVERY citation into a file this
  PR touches rather than one filename: all 48 now resolve (resolver.go x34,
  secrets_service.go x12, go.mod x2).
- resolver.go + secrets_service.go: the `Delete` no-op was rationalized as
  "no CLI verb upstream". True at v0.15.0, false at this pin — `secretspec
  delete` shipped in 0.18 and is in the staged binary. Say the verb exists and
  that wiring it is a deliberate deferral (RIG-3436): it makes the operation
  destructive against a keyspace shared by default, so it needs its own
  F1-guard and ordering analysis. Same correction in the record.
- resolver.go: `defaultCLI` claimed the dev shell and the deployed image both
  stage the binary. Only the dev shell does; nothing stages it into the shipped
  artifact. Narrow the claim to what holds and point at RIG-3437.
- secrets_service_pgtest_test.go: hoist the secret literal so the value-absence
  assertion cannot silently stop testing anything when the input changes.

Refs RIG-3320

Co-authored-by: Matt Wilkinson <matt@rigel.build>

…ot hand-counted (RIG-3320)

Round-4 review found a high. The previous commit re-pointed the
secrets_service.go citations and, in the same commit, edited resolver.go —
adding a line to the defaultCLI comment and three to the Delete comment —
without re-pointing the 34 resolver.go citations. 29 went stale, 7 of them onto
real-but-wrong executable code: resolver.go:171 is cited four times as the
uncancellable FFI `b.Load()` that anchors T2's whole bounded-offload design,
and it had come to resolve to `b = b.WithProfile(profile)`, a pure builder call
with no FFI and nothing to block on. An agent implementing from that reads the
offload machinery as unnecessary. Same class of break on the F1 master-key guard
citation: :218 landed on a comment, one line above the `resolver.Delete` call
it names.

The root cause is not carelessness on any one line, it is that the audit was
done by hand twice and both times scoped to the file I had most recently
thought about. So this pass computes it: diff each touched file against the
last pushed revision, build a parent-line -> head-line map from the matching
blocks, and rewrite every citation through the map. 31 refs moved. Then verify
in the other direction — every cited anchor is checked to still name the
construct the prose says it does (b.Load(), the Set/setArgs signatures,
exec.CommandContext, the F1 pre-call sites, go.mod:22), because in-range is not
the same as correct and only the second check would have caught this.

Also from the review:

- Two F2 passages said the repo "pins ... at v0.15.0" while citing
  go/go.mod:22, which this PR changes to v0.20.0 — the citation contradicted
  the sentence quoting it. Reframed as what it is: the pin as of writing, with
  the bump noted.
- Dropped the value-never-in-argv loop from TestSetArgs. setArgs takes no value
  parameter, so the string it scans for is never in scope and no mutation could
  redden it; it read like the guard while asserting nothing. The comment now
  points at TestSetFeedsValueOnStdinNeverArgv, which spawns a real process and
  checks the child's actual argv.

Refs RIG-3320

Co-authored-by: Matt Wilkinson <matt@rigel.build>

…s too (RIG-3320)

Round-5 review. Last round's fix computed the line map correctly and then
applied it to exactly one document — the record this PR already edits. But the
citations of a shifted file are not confined to the record that happens to
discuss it: resolver.go moved +67 lines and devenv.nix +15, and 81 more
citations of those two files live in sixteen OTHER frozen records this PR never
touched. They were right at the merge base and wrong at head. Same defect as
round 4, one scope level out, and the previous commit message's claim to
'rewrite every citation through the map' described the map's construction
rather than where it got applied.

So the unit of the audit is now the SHIFTED FILE, not the edited document:
build a base->head line map for every code file this stack touches, then sweep
every markdown file in docs/ for citations into any of them. 27 resolver.go
refs across four records (native-client-mode, ownership-layer,
linear-agent-responder, forge-poll-driver) and 54 devenv.nix refs across twelve
more. The worst was the same b.Load() failure round 4 found: native-client-mode
cited resolver.go:162-164 for the WithProvider/WithProfile/Load chain, which at
head is a comment about temp-file cleanup.

Verified by text identity rather than by range, in both directions: for all 156
citation endpoints, the line the base document pointed at and the line the head
document points at are byte-identical. That check is what distinguishes a
correct citation from a merely in-range one, and it is the check that would have
caught both this and the round-4 high.

Two more from the review, both in the record this PR edits:

- The v0.15 reframing fixed the sentence quoting go.mod:22 but left the
  surrounding 'on the current pin' prose meaning v0.15, so each paragraph
  contradicted itself within four lines — stating the bump is done at v0.20.0
  while enumerating the v0.15 capability matrix and calling age:// gated. An
  agent implementing T0/T2's provider wiring could not tell whether the
  record's own ruled default was available. Both paragraphs now speak of v0.15
  in the past tense and state the prerequisite is met.
- The record's one inline spelling of the write command was the pre-PR shape,
  missing the two joined global flags this PR makes mandatory — it taught the
  argv form this PR's own test reddens.

Refs RIG-3320

Co-authored-by: Matt Wilkinson <matt@rigel.build>

…s (RIG-3320)

Round-6 review. Two gaps in the previous sweep, both places its own stated
rule was not actually applied.

The commit message said the audit unit is the shifted FILE rather than the
edited document, then the sweep narrowed to markdown under docs/ — so eight
endpoints in Go source comments were never visited, including the same
b.Load() failure mode the last two rounds each called the worst case:
serve.go cited resolver.go:135-165 for the Resolve->b.Load() span, which at
head is a temp-file-cleanup comment and a defer os.Remove. A citation lives
wherever someone wrote it, and .go comments are a place people write them.
Fixed in serve.go and internal/stack/{spec,config,deps}.go; all four files are
untouched by this PR, so those citations were correct at the merge base and are
regressions this stack introduced.

The rewriter also only re-pointed the FIRST numeric component of a
comma-joined citation, leaving four trailing components at base values — e.g.
devenv.nix:328,383, where the 383 half is the --listen line the sentence is
actually about. The text-identity check missed it by comparing per-citation
rather than per-endpoint, which is the same shape of error: verifying the unit
you happened to iterate over instead of the unit that has to be right.

Both checks are now per-ENDPOINT and prefix-aware. Prefix-awareness matters
because a bare basename match would conflate root devenv.nix with
agent-image/devenv.nix, forks/*/default.nix and guest-image/default.nix, which
this PR does not touch — I verified the previous round shifted none of those.
All 15 endpoints verified by text identity: the line each citation named at the
merge base and the line it names at head are byte-identical.

Refs RIG-3320

Co-authored-by: Matt Wilkinson <matt@rigel.build>

…ot just by it (RIG-3320)

Round 8 verified its rewrites by text identity: the line each citation named at
the merge base and the line it names at head are byte-identical. That claim was
true, and that is exactly the gap. Text identity proves a rewrite tracked the
line shift; it says nothing about whether the citation was correct BEFORE the
shift. Seven citations were already stale on main, so tracking the shift
faithfully preserved the staleness — and rule://planning-evidence asks for the
semantic property, that the cited line names the construct the prose claims.

Re-pointed against the construct each one claims, verified by asserting the
cited line contains the named flag/attr rather than by comparing base to head:

- go/internal/stack/spec.go:19  --runner-id: 293 (a GTK closure comment) ->
  498 for the spawn, :547 for the mint side, the two that must agree.
- go/internal/stack/spec.go:23  serverSpec: 199-205 (skopeo prose) -> 395-400,
  the --socket/--database/--listen/--tls-cert/--tls-key block it mirrors. This
  one round 8 did not touch and no round had flagged.
- go/internal/stack/spec.go:39  runnerSpec: 292-297 (pcClosure let-binding) ->
  497-502, the exec whose flags the comment enumerates.
- go/internal/stack/config.go:123  the 69-byte agent-socket suffix: 270-278
  (pkg-config `.pc` walk prose) -> 479-480, the sentence that states the path
  and the figure. Load-bearing: it grounds a 107-byte sun_path constant.
- go/internal/stack/deps.go:30  postgres ordering: 224-257 (cloud-hypervisor
  and the new secretspec block) -> :362 services.postgres and :386 the
  compass-server process, the two ends of the ordering.
- compass-local-dev/design.md:385  port doors: 275,280 (a `.pc` subdir comment
  and a bare `#`) -> 403,408, the ports.devhttp/ports.network allocations.
- compass-local-dev/design.md:567  runner.token and tls.crt: 343,398 and 347
  (RunSessions prose, container teardown prose) -> :548 mints the token and
  :496 reads it, :529 mints the cert and :500 trusts it.

Verified: all 16 endpoints assert-checked against the flag or attribute the
prose names, 0 mismatches. gofmt clean, go vet and go build pass, internal/stack
tests pass, markdownlint 199 files 0 errors.

Refs RIG-3320

Co-authored-by: Matt Wilkinson <matt@rigel.build>